/* Copyright 2009
 *
 * This program and the accompanying materials
 * are made available under the terms of the
 * Eclipse Public License v1.0 which accompanies
 * this distribution, and is available at
 *
 * 		http://www.eclipse.org/legal/epl-v10.html
 *
 * Unless required by applicable law or agreed to in
 * writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
 * OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing
 * permissions and limitations under the License.
 *
 * Contributors:
 * 	   IBM Corporation - initial API and implementation for JDT/DLTK
 *     Sean W. Quinn - initial adoption for use with PHP from various sources.
 */
package org.eclipse.php.core;

import org.eclipse.core.resources.IResource;
import org.eclipse.core.resources.IWorkspace;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.dltk.core.IOpenable;
import org.eclipse.dltk.core.IParent;
import org.eclipse.dltk.core.IScriptModel;

/**
 * Represent the root PHP element corresponding to the workspace. Since there is
 * only one such root element, it is commonly referred to as <em>the</em> PHP
 * model element. The PHP model element needs to be opened before it can be
 * navigated or manipulated. The PHP model element has no parent (it is the root
 * of the PHP element hierarchy). Its children are <code>IPHPProject</code>s.
 * <p>
 * This interface provides methods for performing copy, move, rename, and delete
 * operations on multiple PHP elements.
 * </p>
 * <p>
 * An instance of one of these handles can be created via
 * <code>PHPCore.create(workspace.getRoot())</code>.
 * </p>
 * 
 * @see PHPCore#create(org.eclipse.core.resources.IWorkspaceRoot)
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IPHPModel extends IScriptModel, IPHPElement, IOpenable, IParent {
	/**
	 * Returns whether this PHP model contains an <code>IPHPElement</code> whose
	 * resource is the given resource or a non-PHP resource which is the given
	 * resource.
	 * <p>
	 * Note: no existency check is performed on the argument resource. If it is
	 * not accessible (see <code>IResource.isAccessible()</code>) yet but would
	 * be located in PHP model range, then it will return <code>true</code>.
	 * </p>
	 * <p>
	 * If the resource is accessible, it can be reached by navigating the PHP
	 * model down using the <code>getChildren()</code> and/or
	 * <code>getNonPHPResources()</code> methods.
	 * </p>
	 * 
	 * @param resource
	 *            the resource to check
	 * @return true if the resource is accessible through the PHP model
	 * @since 2.1
	 */
	boolean contains(IResource resource);

	/**
	 * Copies the given elements to the specified container(s). If one container
	 * is specified, all elements are copied to that container. If more than one
	 * container is specified, the number of elements and containers must match,
	 * and each element is copied to its associated container.
	 * <p>
	 * Optionally, each copy can positioned before a sibling element. If
	 * <code>null</code> is specified for a given sibling, the copy is inserted
	 * as the last child of its associated container.
	 * </p>
	 * <p>
	 * Optionally, each copy can be renamed. If <code>null</code> is specified
	 * for the new name, the copy is not renamed.
	 * </p>
	 * <p>
	 * Optionally, any existing child in the destination container with the same
	 * name can be replaced by specifying <code>true</code> for force. Otherwise
	 * an exception is thrown in the event that a name collision occurs.
	 * </p>
	 * 
	 * @param elements
	 *            the elements to copy
	 * @param containers
	 *            the container, or list of containers
	 * @param siblings
	 *            the list of siblings element any of which may be
	 *            <code>null</code>; or <code>null</code>
	 * @param renamings
	 *            the list of new names any of which may be <code>null</code>;
	 *            or <code>null</code>
	 * @param replace
	 *            <code>true</code> if any existing child in a target container
	 *            with the target name should be replaced, and
	 *            <code>false</code> to throw an exception in the event of a
	 *            name collision
	 * @param monitor
	 *            a progress monitor
	 * @exception PHPModelException
	 *                if an element could not be copied. Reasons include:
	 *                <ul>
	 *                <li>There is no element to process
	 *                (NO_ELEMENTS_TO_PROCESS). The given elements is null or
	 *                empty</li>
	 *                <li>A specified element, container, or sibling does not
	 *                exist (ELEMENT_DOES_NOT_EXIST)</li>
	 *                <li>A <code>CoreException</code> occurred while updating
	 *                an underlying resource</li>
	 *                <li>A container is of an incompatible type (
	 *                <code>INVALID_DESTINATION</code>)</li>
	 *                <li>A sibling is not a child of it associated container (
	 *                <code>INVALID_SIBLING</code>)</li>
	 *                <li>A new name is invalid (<code>INVALID_NAME</code>)</li>
	 *                <li>A child in its associated container already exists
	 *                with the same name and <code>replace</code> has been
	 *                specified as <code>false</code> (
	 *                <code>NAME_COLLISION</code>)</li>
	 *                <li>A container or element is read-only (
	 *                <code>READ_ONLY</code>)</li>
	 *                </ul>
	 */
	void copy(IPHPElement[] elements, IPHPElement[] containers,
			IPHPElement[] siblings, String[] renamings, boolean replace,
			IProgressMonitor monitor) throws PHPModelException;

	/**
	 * Deletes the given elements, forcing the operation if necessary and
	 * specified.
	 * 
	 * @param elements
	 *            the elements to delete
	 * @param force
	 *            a flag controlling whether underlying resources that are not
	 *            in sync with the local file system will be tolerated
	 * @param monitor
	 *            a progress monitor
	 * @exception PHPModelException
	 *                if an element could not be deleted. Reasons include:
	 *                <ul>
	 *                <li>There is no element to process
	 *                (NO_ELEMENTS_TO_PROCESS). The given elements is null or
	 *                empty</li>
	 *                <li>A specified element does not exist
	 *                (ELEMENT_DOES_NOT_EXIST)</li>
	 *                <li>A <code>CoreException</code> occurred while updating
	 *                an underlying resource</li>
	 *                <li>An element is read-only (<code>READ_ONLY</code>)</li>
	 *                </ul>
	 */
	void delete(IPHPElement[] elements, boolean force, IProgressMonitor monitor)
			throws PHPModelException;

	/**
	 * Returns the PHP project with the given name. The given name must be a
	 * valid path segment as defined by {@link IPath#isValidSegment(String)}.
	 * This is a handle-only method. The project may or may not exist.
	 * 
	 * @param name
	 *            the name of the PHP project
	 * @return the PHP project with the given name
	 */
	IPHPProject getPHPProject(String name);

	/**
	 * Returns the PHP projects in this PHP model, or an empty array if there
	 * are none.
	 * 
	 * @return the PHP projects in this PHP model, or an empty array if there
	 *         are none
	 * @exception PHPModelException
	 *                if this request fails.
	 */
	IPHPProject[] getPHPProjects() throws PHPModelException;

	/**
	 * Returns an array of non-PHP resources (that is, non-PHP projects) in the
	 * workspace.
	 * <p>
	 * Non-PHP projects include all projects that are closed (even if they have
	 * the PHP nature).
	 * </p>
	 * 
	 * @return an array of non-PHP projects (<code>IProject</code>s) contained
	 *         in the workspace.
	 * @throws PHPModelException
	 *             if this element does not exist or if an exception occurs
	 *             while accessing its corresponding resource
	 * @since 2.1
	 */
	Object[] getNonPHPResources() throws PHPModelException;

	/**
	 * Returns the workspace associated with this PHP model.
	 * 
	 * @return the workspace associated with this PHP model
	 */
	IWorkspace getWorkspace();

	/**
	 * Moves the given elements to the specified container(s). If one container
	 * is specified, all elements are moved to that container. If more than one
	 * container is specified, the number of elements and containers must match,
	 * and each element is moved to its associated container.
	 * <p>
	 * Optionally, each element can positioned before a sibling element. If
	 * <code>null</code> is specified for sibling, the element is inserted as
	 * the last child of its associated container.
	 * </p>
	 * <p>
	 * Optionally, each element can be renamed. If <code>null</code> is
	 * specified for the new name, the element is not renamed.
	 * </p>
	 * <p>
	 * Optionally, any existing child in the destination container with the same
	 * name can be replaced by specifying <code>true</code> for force. Otherwise
	 * an exception is thrown in the event that a name collision occurs.
	 * </p>
	 * 
	 * @param elements
	 *            the elements to move
	 * @param containers
	 *            the container, or list of containers
	 * @param siblings
	 *            the list of siblings element any of which may be
	 *            <code>null</code>; or <code>null</code>
	 * @param renamings
	 *            the list of new names any of which may be <code>null</code>;
	 *            or <code>null</code>
	 * @param replace
	 *            <code>true</code> if any existing child in a target container
	 *            with the target name should be replaced, and
	 *            <code>false</code> to throw an exception in the event of a
	 *            name collision
	 * @param monitor
	 *            a progress monitor
	 * @exception PHPModelException
	 *                if an element could not be moved. Reasons include:
	 *                <ul>
	 *                <li>There is no element to process
	 *                (NO_ELEMENTS_TO_PROCESS). The given elements is null or
	 *                empty</li>
	 *                <li>A specified element, container, or sibling does not
	 *                exist (ELEMENT_DOES_NOT_EXIST)</li>
	 *                <li>A <code>CoreException</code> occurred while updating
	 *                an underlying resource</li>
	 *                <li>A container is of an incompatible type (
	 *                <code>INVALID_DESTINATION</code>)</li>
	 *                <li>A sibling is not a child of it associated container (
	 *                <code>INVALID_SIBLING</code>)</li>
	 *                <li>A new name is invalid (<code>INVALID_NAME</code>)</li>
	 *                <li>A child in its associated container already exists
	 *                with the same name and <code>replace</code> has been
	 *                specified as <code>false</code> (
	 *                <code>NAME_COLLISION</code>)</li>
	 *                <li>A container or element is read-only (
	 *                <code>READ_ONLY</code>)</li>
	 *                </ul>
	 * 
	 * @exception IllegalArgumentException
	 *                any element or container is <code>null</code>
	 */
	void move(IPHPElement[] elements, IPHPElement[] containers,
			IPHPElement[] siblings, String[] renamings, boolean replace,
			IProgressMonitor monitor) throws PHPModelException;

	/**
	 * Triggers an update of the PHPModel with respect to the referenced
	 * external archives. This operation will issue a PHPModel delta describing
	 * the discovered changes, in term of PHP element package fragment roots
	 * added, removed or changed. Note that a collection of elements can be
	 * passed so as to narrow the set of archives to refresh (passing
	 * <code>null</code> along is equivalent to refreshing the entire mode). The
	 * elements can be:
	 * <ul>
	 * <li>package fragment roots corresponding to external archives
	 * <li>PHP projects, which referenced external archives will be refreshed
	 * <li>PHP model, all referenced external archives will be refreshed.
	 * </ul>
	 * <p>
	 * In case an archive is used by multiple projects, the delta issued will
	 * account for all of them. This means that even if a project was not part
	 * of the elements scope, it may still be notified of changes if it is
	 * referencing a library comprised in the scope.
	 * <p>
	 * 
	 * @param elementsScope
	 *            - a collection of elements defining the scope of the refresh
	 * @param monitor
	 *            - a progress monitor used to report progress
	 * @exception PHPModelException
	 *                in one of the corresponding situation:
	 *                <ul>
	 *                <li> an exception occurs while accessing project resources
	 *                </li>
	 *                </ul>
	 * 
	 * @see IPHPElementDelta
	 * @since 2.0
	 */
	void refreshExternalArchives(IPHPElement[] elementsScope,
			IProgressMonitor monitor) throws PHPModelException;

	/**
	 * Renames the given elements as specified. If one container is specified,
	 * all elements are renamed within that container. If more than one
	 * container is specified, the number of elements and containers must match,
	 * and each element is renamed within its associated container.
	 * 
	 * @param elements
	 *            the elements to rename
	 * @param destinations
	 *            the container, or list of containers
	 * @param names
	 *            the list of new names
	 * @param replace
	 *            <code>true</code> if an existing child in a target container
	 *            with the target name should be replaced, and
	 *            <code>false</code> to throw an exception in the event of a
	 *            name collision
	 * @param monitor
	 *            a progress monitor
	 * @exception PHPModelException
	 *                if an element could not be renamed. Reasons include:
	 *                <ul>
	 *                <li>There is no element to process
	 *                (NO_ELEMENTS_TO_PROCESS). The given elements is null or
	 *                empty</li>
	 *                <li>A specified element does not exist
	 *                (ELEMENT_DOES_NOT_EXIST)</li>
	 *                <li>A <code>CoreException</code> occurred while updating
	 *                an underlying resource
	 *                <li>A new name is invalid (<code>INVALID_NAME</code>)
	 *                <li>A child already exists with the same name and
	 *                <code>replace</code> has been specified as
	 *                <code>false</code> (<code>NAME_COLLISION</code>)
	 *                <li>An element is read-only (<code>READ_ONLY</code>)
	 *                </ul>
	 */
	void rename(IPHPElement[] elements, IPHPElement[] destinations,
			String[] names, boolean replace, IProgressMonitor monitor)
			throws PHPModelException;

}
